Creating Video Digitizer Components(IM: QC)

Inside Macintosh: QuickTime Components /: Chapter 8 - Video Digitizer Components

Creating Video Digitizer Components
Video digitizer components are the most convenient mechanism for presenting new sources of video data to QuickTime. For example, if you are developing special-purpose video hardware that digitizes video images from a previously unsupported source device, you should create a video digitizer component so that applications or sequence grabber components can obtain data from your device.
Refer to the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for a general discussion of how to create a component.
The remaining topics in this section discuss issues you should consider when creating a video digitizer component.
Apple has defined a functional interface for video digitizer components. For information about the functions your digitizer component must support, see "Video Digitizer Component Functions" beginning on page 8-23.
You can use the following enumerators to refer to the request codes for each of the functions that your component must support.
enum {
   /* video digitizer interface */
   kSelectVDGetMaxSrcRect              = 0x1,/* VDGetMaxSrcRect (required) */
   kSelectVDGetActiveSrcRect           = 0x2,/* VDGetActiveSrcRect 
                                                (required) */
   kSelectVDSetDigitizerRect           = 0x3,/* VDSetDigitizerRect 
                                                (required) */
   kSelectVDGetDigitizerRect           = 0x4,/* VDGetDigitizerRect 
                                                (required) */
   kSelectVDGetVBlankRect              = 0x5,/* VDGetVBlankRect (required) */
   kSelectVDGetMaskPixMap              = 0x6,/* VDGetMaskPixMap */
   kSelectVDGetPlayThruDestination     = 0x8,/* VDGetPlayThruDestination
                                                (required) */
   kSelectVDUseThisCLUT                = 0x9,/* VDUseThisCLUT */
   kSelectVDSetInputGammaValue         = 0xA,/* VDSetInputGammaValue */
   kSelectVDGetInputGammaValue         = 0xB,/* VDGetInputGammaValue */
   kSelectVDSetBrightness              = 0xC,/* VDSetBrightness */
   kSelectVDGetBrightness              = 0xD,/* VDGetBrightness */
   kSelectVDSetContrast                = 0xE,/* VDSetContrast */
   kSelectVDSetHue                     = 0xF,/* VDSetHue */
   kSelectVDSetSharpness               = 0x10,/* VDSetSharpness */
   kSelectVDSetSaturation              = 0x11,/* VDSetSaturation */
   kSelectVDGetContrast                = 0x12,/* VDGetContrast */
   kSelectVDGetHue                     = 0x13,/* VDGetHue */
   kSelectVDGetSharpness               = 0x14,/* VDGetSharpness */
   kSelectVDGetSaturation              = 0x15,/* VDGetSaturation */
   kSelectVDGrabOneFrame               = 0x16,/* VDGrabOneFrame 
                                                (required) */
   kSelectVDGetMaxAuxBuffer            = 0x17,/* VDGetMaxAuxBuffer */
   kSelectVDGetDigitizerInfo           = 0x19,/* VDGetDigitizerInfo 
                                                (required) */
   kSelectVDGetCurrentFlags            = 0x1A,/* VDGetCurrentFlags
                                                (required) */
   kSelectVDSetKeyColor                = 0x1B,/* VDSetKeyColor */
   kSelectVDGetKeyColor                = 0x1C,/* VDGetKeyColor */
   kSelectVDAddKeyColor                = 0x1D,/* VDAddKeyColor */
   kSelectVDGetNextKeyColor            = 0x1E,/* VDGetNextKeyColor */
   kSelectVDSetKeyColorRange           = 0x1F,/* VDSetKeyColorRange */
   kSelectVDGetKeyColorRange           = 0x20,/* VDGetKeyColorRange */
   kSelectVDSetDigitizerUserInterrupt  = 0x21,
                                          /* VDSetDigitizerUserInterrupt */
   kSelectVDSetInputColorSpaceMode     = 0x22,/* VDSetInputColorSpaceMode */
   kSelectVDGetInputColorSpaceMode     = 0x23,/* VDGetInputColorSpaceMode */
   kSelectVDSetClipState               = 0x24,/* VDSetClipState */
   kSelectVDSetClipState               = 0x25,/* VDGetClipState */
   kSelectVDSetClipRgn                 = 0x26,/* VDSetClipRgn */
   kSelectVDClearClipRgn               = 0x27,/* VDClearClipRgn */
   kSelectVDGetCLUTInUse               = 0x28,/* VDGetCLUTInUse */
   kSelectVDSetPLLFilterType           = 0x29,/* VDSetPLLFilterType */
   kSelectVDGetPLLFilterType           = 0x2A,/* VDGetPLLFilterType */
   kSelectVDGetMaskandValue            = 0x2B,/* VDGetMaskandValue */
   kSelectVDSetMasterBlendLevel        = 0x2C,/* VDSetMasterBlendLevel */
   kSelectVDSetPlayThruDestination     = 0x2D,/* VDSetPlayThruDestination */
   kSelectVDSetPlayThruOnOff           = 0x2E,/* VDSetPlayThruOnOff */
   kSelectVDSetFieldPreference         = 0x2F,/* VDSetFieldPreference
                                                (required) */
   kSelectVDGetFieldPreference         = 0x30,/* VDGetFieldPreference
                                                (required) */
   kSelectVDPreflightDestination       = 0x32,/* VDPreflightDestination
                                                (required) */
   kSelectVDPreflightGlobalRect        = 0x33,/* VDPreflightGlobalRect */
   kSelectVDSetPlayThruGlobalRect      = 0x34,/* VDSetPlayThruGlobalRect */
   kSelectVDSetInputGammaRecord        = 0x35,/* VDSetInputGammaRecord */
   kSelectVDGetInputGammaRecord        = 0x36,/* VDGetInputGammaRecord */
   kSelectVDSetBlackLevelValue         = 0x37,/* VDSetBlackLevelValue */
   kSelectVDGetBlackLevelValue         = 0x38,/* VDGetBlackLevelValue */
   kSelectVDSetWhiteLevelValue         = 0x39,/* VDSetWhiteLevelValue */
   kSelectVDGetWhiteLevelValue         = 0x3A,/* VDGetWhiteLevelValue */
   kSelectVDGetVideoDefaults           = 0x3B,/* VDGetVideoDefaults */
   kSelectVDGetNumberOfInputs          = 0x3C,/* VDGetNumberOfInputs */
   kSelectVDGetInputFormat             = 0x3D,/* VDGetInputFormat */
   kSelectVDSetInput                   = 0x3E,/* VDSetInput */
   kSelectVDGetInput                   = 0x3F,/* VDGetInput */
   kSelectVDSetInputStandard           = 0x40,/* VDSetInputStandard */
   kSelectVDSetupBuffers               = 0x41,/* VDSetupBuffers */
   kSelectVDGrabOneFrameAsync          = 0x42,/* VDGrabOneFrameAsync */
   kSelectVDDone                       = 0x43,/* VDDone */
   kSelectVDSetCompression             = 0x44,/* VDSetCompression */
   kSelectVDCompressOneFrameAsync      = 0x45,/* VDCompressOneFrameAsync */
   kSelectVDCompressDone               = 0x46,/* VDCompressDone */
   kSelectVDReleaseCompressBuffer      = 0x47,/* VDReleaseCompressBuffer */
   kSelectVDGetImageDescription        = 0x48,/* VDGetImageDescription */
   kSelectVDResetCompressSequence      = 0x49,/* VDResetCompressSequence */
   kSelectVDSetCompressionOnOff        = 0x4A,/* VDSetCompressionOnOff */
   kSelectVDGetCompressionTypes        = 0x4B,/* VDGetCompressionTypes */
   kSelectVDSetTimeBase                = 0x4C,/* VDSetTimeBase */
   kSelectVDSetFrameRate               = 0x4D,/* VDSetFrameRate */
   kSelectVDGetDataRate                = 0x4E,/* VDGetDataRate */
   kSelectVDGetSoundInputDriver        = 0x4F,/* VDGetSoundInputDriver */
   kSelectVDGetDMADepths               = 0x50,/* VDGetDMADepths */
   kSelectVDGetPreferredTimeScale      = 0x51,/* VDGetPreferredTimeScale */
   kSelectVDReleaseAsyncBuffers        = 0x52,/* VDReleaseAsyncBuffers */
};
Component Type and Subtype Values
Apple has defined a type value for video digitizer components. All video digitizer components have a component type value of 'vdig'. You can use the following constant to specify the component type value.
#define videoDigitizerComponentType = 'vdig'
There are no special conventions applied to the subtype value of video digitizer components.

Required Functions
Video digitizer components support a rich functional interface that can accommodate devices with quite varied capabilities. To relieve you from having to support irrelevant functions, Apple has made several video digitizer functions optional.
At a minimum, your video digitizer component must support the following functions:
VDGetActiveSrcRect VDGetCurrentFlags
VDGetDigitizerInfo VDGetDigitizerRect
VDGetFieldPreference VDGetInput
VDGetInputFormat VDGetMaxSrcRect
VDGetNumberOfInputs VDGetPlayThruDestination
VDGetVBlankRect VDGetVideoDefaults
VDGrabOneFrame VDPreflightDestination
VDSetDigitizerRect VDSetFieldPreference
VDSetInput VDSetInputStandard
VDSetPlayThruDestination

All of these functions are required for all video digitizer components.

Optional Functions
Based on the type of device your component supports, you may have to implement functions other than those listed in "Required Functions," and you may have to set some of your component's capability flags. Read this section to learn which additional functions your component needs to support and how to set your capability flags properly.
If your component does not support a particular function, be sure to return a result code value of digiUnimpErr.

Note
Hardware support for the simultaneous capture and display of frames on the screen is called playthrough in these sections.

Frame Grabbers Without Playthrough
Suppose your video digitization hardware grabs frames but cannot simultaneously display the frames on the screen. Suppose also that your hardware supplies the grabbed frames in QuickDraw pixel maps at specific pixel depths (say, 16 and 32 bits per pixel). For details on QuickDraw pixel maps, see the chapter "Basic QuickDraw" in Inside Macintosh: Imaging.
In this case, you should set the following component capability flags:

digiOutDoes16
Set this flag to 1.
digiOutDoes32
Set this flag to 1.

Set other depth flags to 0.
digiOutDoesHWPlayThru
Set this flag to 0.
digiOutDoesDMA
Set this flag to 0.
If your component can operate asynchronously, you should also set the following flag:

digiOutDoesAsyncGrabs
Set this flag to 1 if your component can operate asynchronously.
Frame grabbers that support asynchronous operation must support the following optional functions:
VDDone VDGrabOneFrameAsync
VDReleaseAsyncBuffers VDSetupBuffers

Frame Grabbers With Hardware Playthrough
If your frame grabber hardware provides support for playing the captured images directly, you need to support one additional function beyond those discussed in "Frame Grabbers Without Playthrough." The VDSetPlayThruOnOff function (described on page 8-53) allows the application to turn playthrough on and off.
You should also set the digiOutDoesHWPlayThru capability flag (described on page 8-18) to 1. In addition, be sure to use the gdh field in the digitizer information structure to identify your component's display device. For details on the video digitizer information structure, see page 8-20.

Key Color and Alpha Channel Devices
As a further elaboration on a basic frame grabber, your device could support the display or mixing of output data via an alpha channel or through the use of key colors (see "Types of Video Digitizer Components" on page 8-5 for more information about alpha channels and key colors). In either case, image data cannot be read directly from the screen. Therefore, you must set the digiOutDoesUnreadableScreenBits capability flag to 1. For more on the video digitizer capability flags, see "Capability Flags" beginning on page 8-14.
Your component must load its alpha channel or fill in the key color whenever playthrough is enabled or when the destination changes.

Compressed Source Devices
You may create a video digitizer component that supports a device that delivers compressed image data. In this case, your component is not capable of displaying the data directly.
Your component should set the following capability flags:

digiOutDoesCompress
Set this flag to 1.
digiOutDoesCompressOnly
Set this flag to 1 if your component cannot display the images directly.
digiOutDoesPlayThruDuringCompress
Set this flag to 1 if your component cannot display the images directly.
In addition, frame grabbers that support compressed source devices must support the following optional functions:
VDCompressDone VDCompressOneFrameAsync
VDGetCompressionTypes VDGetDataRate
VDGetImageDescription VDResetCompressSequence
VDSetCompression VDSetCompressionOnOff
VDSetFrameRate VDSetTimeBase

If your hardware generates compressed data that cannot be decompressed by any standard QuickTime image decompressor components, be sure to provide an appropriate decompressor component so that the data you provide can be displayed.

Subtopics
Component Type and Subtype Values

Required Functions

Optional Functions

Frame Grabbers Without Playthrough

Frame Grabbers With Hardware Playthrough

Key Color and Alpha Channel Devices

Compressed Source Devices

VDGetActiveSrcRect	VDGetCurrentFlags
VDGetDigitizerInfo	VDGetDigitizerRect
VDGetFieldPreference	VDGetInput
VDGetInputFormat	VDGetMaxSrcRect
VDGetNumberOfInputs	VDGetPlayThruDestination
VDGetVBlankRect	VDGetVideoDefaults
VDGrabOneFrame	VDPreflightDestination
VDSetDigitizerRect	VDSetFieldPreference
VDSetInput	VDSetInputStandard
VDSetPlayThruDestination

VDDone	VDGrabOneFrameAsync
VDReleaseAsyncBuffers	VDSetupBuffers

VDCompressDone	VDCompressOneFrameAsync
VDGetCompressionTypes	VDGetDataRate
VDGetImageDescription	VDResetCompressSequence
VDSetCompression	VDSetCompressionOnOff
VDSetFrameRate	VDSetTimeBase